TIN Check API

Objective

The TIN Check API returns the basic details associated with a Tax Identification Number (TIN).

Input	Output
The user's or organisation's TIN	The details corresponding to the given TIN. The complete list of output fields is provided under the Success Response Details section.

API Endpoint

TINCheck

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files as form-data through a POST request.

Authentication

You need a unique pair of application ID (appId) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

API Request Details

Method - POST

Headers

Parameter	Mandatory or Optional	Description	Allowed Values
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
transactionId	Mandatory	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

Input

The following table provides the complete information on the parameter used in the request body for the API calls.

Parameter	Description	Mandatory or Optional	Allowed Values	Default Value
tinNumber	The Tax Identification Number	Mandatory	Type: String Format: 12345678-1234	Not Applicable

Sample Request

The following code shows a standard cURL request for the API.

curl --location --request POST 'https://zaf.thomas.hyperverge.co/v1/TINCheck' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "tinNumber": "<Enter_the_TIN>"
}'

Success Response Sample

The following code is a sample of success response from the API.

{
    "status": "success",
    "statusCode": "200",
    "result": {
        "data": {
            "taxpayerName": "<Name_of_the_User>",
            "cacRegNumber": "<Registration_Number>",
            "tinNumber": "<Taxpayer_Identification_Number>",
            "jittin": null,
            "taxOffice": "<Tax_Office>",
            "phoneNumber": "<Phone_Number>",
            "email": "<Email_Address>",
            "tinType": "<Taxpayer_Type>"
        }
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Success Response Details

Parameter	Type	Description
taxpayerName	string	The name of the taxpayer
cacRegNumber	string	The Corporate Affairs Commission(CAC) registration number of the taxpayer
tinNumber	string	The Tax Identification Number
jittin	string	The Joint Income Tax Identification Number
taxOffice	string	The tax office responsible for the taxpayer
phoneNumber	string	The phone number of the taxpayer
email	string	The email address of the taxpayer
tinType	string	The type of the TIN (Individual/Corporate)

Error Response Samples

Invalid TIN

{
    "status": "failure",
    "statusCode": 400,
    "error": "Please provide a valid TIN Number",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Invalid TIN Format

{
    "status": "failure",
    "statusCode": 400,
    "error": "TIN must be in the format 12345678-1234, please check and retry",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Blank TIN

{
    "status": "failure",
    "statusCode": 400,
    "error": "The provided TIN number is empty,please provide a valid TIN  Number",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Missing/Invalid Credentials

{
    "message": "Missing/Invalid credentials",
    "statusCode": 401,
    "status": "failure"
}

Internal Server Error

{
    "status": "failure",
    "statusCode": 500,
    "error": "Internal Server Error",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Error Response Details

A failure or error response from the module contains a failure status, with a relavant status code and error message. The following table lists all error responses.

Status Code	Error Message	Error Description
400	Please provide a valid TIN	The provided TIN number is invalid
400	TIN must be in the format 12345678-1234, please check and retry	The provided TIN number isn't in the valid format
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values
403	Access Denied	Please contact the HyperVerge team for resolution
500	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution